Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Converting Between Unicode and Pascal Strings /

ConvertFromPStringToUnicode

Converts a Pascal string in a Mac OS text encoding to a Unicode string.

pascal OSStatus ConvertFromPStringToUnicode (
      TextToUnicodeInfo iTextToUnicodeInfo,
      ConstStr255Param iPascalStr, 
      ByteCount iOutputBufLen, 
      ByteCount *oUnicodeLen, 
      UniCharArrayPtr oUnicodeStr);

iTextToUnicodeInfo

A Unicode converter object of type TextToUnicodeInfo (page 119) for the Pascal string to be converted. You can use the function CreateTextToUnicodeInfo (page 125) or CreateTextToUnicodeInfoByEncoding (page 127) to create the Unicode converter object.

iPascalStr

The Pascal string to be converted to Unicode.

iOutputBufLen

The length in bytes of the output buffer pointed to by the oUnicodeStr parameter. Your application supplies this buffer to hold the returned converted string. The oUnicodeLen parameter may return a byte count that is less than this value if the converted string is smaller than the buffer size you allocated.

oUnicodeLen

A pointer to a value of type ByteCount. On output, the length in bytes of the converted Unicode string returned in the oUnicodeStr parameter.

oUnicodeStr

A pointer to a Unicode character array. On output, this buffer holds the converted Unicode string. For information on the Unicode character array, see "Unicode Character and String Pointer Data Types" (page 48).

function result

A result code. The function returns the noErr result code if it has completely converted the Pascal string to Unicode without using fallback characters. If the function returns the paramErr, kTECTableFormatErr, or kTECGlobalsUnavailableErr result codes, it did not convert the string.

If the function returns kTECBufferBelowMinimumSizeErr, the output buffer was too small to allow conversion of any part of the input string. You need to increase the size of the output buffer and try again.

If the function returns the kTECUsedFallbacksStatus result code, the function has completely converted the Pascal string using one or more fallback characters.

If the function returns kTECOutputBufferFullErr, the output buffer was not big enough to completely convert the input. You can call the function again with another output buffer--or with the same output buffer, after copying its contents--to convert the remainder of the input string.

If the function returns kTECPartialCharErr, the input buffer ended with an incomplete multibyte character. If you have subsequent input text available, you can append the unconverted input from this call to the beginning of the subsequent input text and call the function again.

See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference" for other possible values.

DISCUSSION

The ConvertFromPStringToUnicode function provides an easy and efficient way to convert a short Pascal string to a Unicode string without incurring the overhead associated with the function ConvertFromTextToUnicode (page 129).

If necessary, this function automatically uses fallback characters to map the text elements of the string.